Fiat Instructions

Fiat Instructions allow your customers to deposit and withdraw traditional currencies (ARS, MXN) using local banking rails. This feature bridges the gap between traditional finance and digital assets, enabling seamless conversions.

Overview

Fiat Instructions come in two types:

Supported Currencies

How It Works

Incoming Fiat Instructions (Deposits)

Incoming fiat instructions generate dedicated virtual accounts for your customers. When customers transfer fiat to these accounts, the funds are automatically converted to stablecoins.

Customer Bank Account → CVU/CLABE → Lirium → Stablecoin Credit

Flow:

1. Create an incoming fiat instruction for your customer
2. Lirium generates a dedicated CVU (Argentina) or CLABE (Mexico)
3. Customer transfers fiat from their bank to the provided account
4. Lirium detects the deposit and converts it to the corresponding stablecoin
5. Stablecoins are credited to the customer's balance

For implementation details, see Create Incoming Fiat Instruction.

Outgoing Fiat Instructions (Withdrawals)

Outgoing fiat instructions register your customer's bank accounts for withdrawals. When customers want to cash out, they can withdraw stablecoins to their registered bank accounts.

Stablecoin Debit → Lirium → CBU/CLABE/Alias → Customer Bank Account

Flow:

1. Create an outgoing fiat instruction with the customer's bank details
2. Lirium validates and stores the banking information
3. When the customer wants to withdraw, create a sell order with the instruction ID
4. Lirium converts stablecoins to fiat and transfers to the registered bank account

{
  "reference_id": "withdrawal-123",
  "operation": "sell",
  "asset": {
    "currency": "MXNB",
    "amount": "101.00"
  },
  "sell": {
    "payment": {
      "destination": {
        "type": "fiat_instructions",
        "value": "39c98c5ae53941449539074a2645dd85"
      }
    }
  }
}

For implementation details, see Create Outgoing Fiat Instruction.

Integration Guide

Step 1: Customer Onboarding

Before creating fiat instructions, ensure your customer is fully onboarded and verified. See KYC Flows for details on customer verification requirements.

Step 2: Create Deposit Instructions

To enable deposits for a customer, create an incoming fiat instruction:

POST /customers/{customer_id}/incoming_fiat_instructions

{
  "type": "ar_cvu",
  "currency": "ARS"
}

The response includes the generated payment details (CVU, alias) that you should display to your customer.

Step 3: Register Withdrawal Accounts

To enable withdrawals, register the customer's bank account:

POST /customers/{customer_id}/outgoing_fiat_instructions

{
  "currency": "ARS",
  "type": "ar_cbu",
  "label": "Primary Bank Account",
  "data": {
    "cbu": "1234567890123456789012",
    "cuit": "20123456789"
  }
}

Step 4: Monitor Transactions

Use webhooks to receive real-time notifications about:

• Incoming deposits (incoming-funds event)
• Order status changes (order-updated event)

Payment Rail Details

Argentina (ARS)

CVU (Clave Virtual Uniforme) - Deposits

A CVU is a 22-digit virtual account number used in Argentina's instant payment system. Each customer receives a unique CVU for deposits.

CBU (Clave Bancaria Uniforme) - Withdrawals

A CBU is a 22-digit bank account number used for traditional bank transfers.

Alias - Withdrawals

An alias is a human-readable identifier linked to a bank account.

Mexico (MXN)

CLABE (Clave Bancaria Estandarizada)

An 18-digit standardized bank account number used for interbank transfers in Mexico.

Best Practices

1. Store instruction IDs: Save the instruction IDs returned by the API for future reference and withdrawals.

2. Display payment details clearly: When showing CVU/CLABE to customers, format them for readability and include copy-to-clipboard functionality.

3. Validate before submission: Validate CBU (22 digits), CLABE (18 digits), and CUIT (11 digits) formats client-side before API calls.

4. Handle webhooks idempotently: Deposit notifications may be delivered multiple times. Use the event ID to deduplicate.

5. Label instructions descriptively: Use meaningful labels for outgoing instructions (e.g., "Santander Savings Account") to help customers identify their accounts.

API Reference

• Get Incoming Fiat Instructions
• Create Incoming Fiat Instruction
• Get Outgoing Fiat Instructions
• Create Outgoing Fiat Instruction